Add Deep Core Style#4925
Conversation
Replaces SPACETIME_PROGRAMMING_STANDARDS.md with DEEP_CORE_STYLE.md. The document is reorganized around seven principles for the core (datastore, commitlog, snapshotting, replication): 1. Work towards zero dependencies 2. Work towards deterministic simulation testing 3. Work towards thread-per-core 4. Work towards no_std 5. Think in terms of persistent data structures 6. Think in terms of pipelining 7. Think in terms of unreliable processes A short style section follows the principles, covering assertions, bounded loops and queues, error handling, control flow, naming, and formatting.
|
|
||
| ## 4. Work towards `no_std` | ||
|
|
||
| To control our failure modes, we should enforce no memory allocation inside the core. This is not absolute. Primitives like pages can be allocated outside the core and passed in. But the rule is that the deep core does not allocate. |
There was a problem hiding this comment.
I think the natural way to do this is to be generic over an allocator trait. Otherwise, this is probably going to be very intrusive in the datastore.
|
|
||
| ## 5. Think in terms of persistent data structures | ||
|
|
||
| We want to support time-travel APIs, sub-transactions, background snapshotting, and potentially MVCC. Persistent data structures, such as Merkle trees and Postgres-style MVCC, naturally allow us to look at multiple versions of data and update versions atomically. |
There was a problem hiding this comment.
(We are deeply committed to mutable non-persistent structures in the datastore right now.)
|
|
||
| We should model the core's communication with the outside world (Tokio, disk I/O, networking, peers) as unreliable, asynchronous message passing. | ||
|
|
||
| This sharpens our error handling. Every message can be lost, delayed, or reordered, and the core's logic must remain correct under those conditions. It is also a natural fit with principle 6, since messages to other processes are inherently pipelined. |
There was a problem hiding this comment.
How about corruption and protection against cosmic rays?
|
|
||
| - Every loop has a static upper bound. If a loop must not terminate (an event loop, for example), that fact is itself asserted. | ||
| - Every queue has a fixed capacity. The deep core does not allocate to absorb load. | ||
| - No recursion in the deep core. |
There was a problem hiding this comment.
(This is currently done in many places in the datastore where we tree-walk AVs and ATs.)
|
|
||
| ### Control flow | ||
|
|
||
| Prefer simple, explicit control flow. Split compound conditions into nested `if/else` rather than chaining them. State invariants positively. Avoid macros where a function will do. |
There was a problem hiding this comment.
I don't think this necessarily makes code simpler to read or more fault tolerant. It can often lead to more repetition and error prone code as a result.
There was a problem hiding this comment.
I concur on the macro part, tho.
There was a problem hiding this comment.
Yes, agreed on the macros part.
|
|
||
| Prefer simple, explicit control flow. Split compound conditions into nested `if/else` rather than chaining them. State invariants positively. Avoid macros where a function will do. | ||
|
|
||
| ### Naming |
There was a problem hiding this comment.
I think this section can be cut. The standard Rust conventions should apply.
|
|
||
| ### Comments and formatting | ||
|
|
||
| - Comments explain *why*, not *what*. The code already says *what*. |
There was a problem hiding this comment.
I think "what"-paragraph-comments are also useful, as they can allow skipping sections of code by summarizing what they do. Why-comments are more valuable of course.
4 participants
Summary
Adds
docs/DEEP_CORE_STYLE.md, a style guide for the core of SpacetimeDB (datastore, commitlog, snapshotting, replication).Read the rendered document
The document is organized around seven principles:
no_stdA short style section follows the principles, covering assertions, bounded loops and queues, error handling, control flow, naming, and formatting. Inspired by TIGER STYLE, narrowed and adapted for Rust and our principles.
This is a seed document. It will grow as we make the principles operational in code and as the practices that serve them become clearer with use.
Test plan